'.\" t
.TH "clform" "1M" "Jun 23, 2006" "1\&.2\&.0"
.SH NAME
clform \- Linuxha Cluster Formation tool

.SH SYNOPSIS
.TS
l.
clform [\fB--force\fP] [\fB--noapps\fP] [\fB--config\fP \fIfile\fP]
       [\fB--nolocking\fP] [\fB--timeout\fP \fIsecs\fP] [\fB--nochecksums\fP]
       [\fB--debug\fP]
       Form a new cluster

clform \fB--join\fP [\fB--force\fP] [\fB--nolocking\fP] [\fB--timeout\fP \fIsecs\fP]
       [\fB--nochecksums\fP] [\fB--debug\fP]
       Join an existing cluster

clform \fB-?\fP
       Show brief usage information
.TE

.SH DESCRIPTION
This utility is designed to allow the formation of clusters as simply
as possible. The list of command line arguments supported is quite
limited to reflect the high-level nature of this command.

The typical usage of running this is command is simply to specify the
command without any arguments - causing the two nodes to attempt to form 
the cluster.

Some output is always sent to the standard output showing the progress
of the command. Unless there are problems cluster formations takes less
than 10 seconds with typical hardware/software configurations.
If one of the nodes is not available, then it may take
as long as the timeout value defined for the cluster, after which a
failure message will be shown.

If the other server is in the cluster is not available then this tool will
fail unless forced to start - see the \fB--force\fP option below for
more details. 

However under normal conditions it is expected that one of the servers 
in the cluster will include this in the it's startup to ensure the cluster
automatically forms when the server reboots - though the \fIclstart(1M)\fP
command may be optionally used instead. Of course it is perfectly acceptable
to run the command directly at the command prompt. 

When this command returns (it may take some time if the other node is
not available), then the cluster will have been formed or failed to form - 
a message on the standard output will of course indicate which.

If any registered applications are set to autostart then if the cluster 
is being formed [rather than joined], start-up of these applications will be
attempted if cluster formation is successful. 

.SH ARGUMENTS
Currently the \fIclform(1M)\fP utility supports the following command 
line arguments:

.TP 4
.B --force
Force the formation or joining of the cluster. This flag will ensure that a 
cluster is formed, or the remainined node joins an existing cluster even if 
the system time difference between them is larger than 10 minutes.
Using this flag will also allow the formation of a cluster even if 
only one of the nodes is available after the specified timeout period.
.TP
.B --noapps
Once the cluster is formed do not attempt to start any applications that are
configured to automatically start on cluster formation.
.TP
.B --join
If the specified cluster is already running allow the other node to join the
running cluster. This command can be run on either of the nodes whether
they are currently the one running as the cluster or not.
.TP
.B --config
This allows the specification of an alternative configuration file rather
than the default \fB/etc/cluster/clconf.xml\fP. This is typically used for
development purposes and can be effectively ignored in most cases.
.TP
.B --timeout
Override the cluster configuration timeout defined in the cluster file
definition with this value, (given in seconds). This is the period of
time the software will wait for a node in the cluster before assuming it 
is not available to form or join the cluster.
.TP
.B --nolocking
Indicate that the cluster daemons should not advertise locking. If the
cluster is already running and the new node is joining the cluster this
option may result in one node with locking and one without - this is 
supported, though all use of the \fB--nolocking\fP flag should be carefully
considered.
.TP
.B --nochecksums
Normally if the cluster or application configuration file 
have been modified whilst the cluster is running the
checksums which are used to indicate the last sane and checked configuration 
will not be valid. In such instances many of the Linuxha.net commands, including
this will not will not function. If necessary the \fB--nochecksums\fP can be
used to overcome this until the cluster or application configuration are
next rebuilt.
.TP
.B --debug
Starts the relevant cluster daemons in 'debug' mode - this is not recommended
for general use but is ideal when attempting to diagnose problems since it
generates a lot more output when events occur.

.SH AUTOMATIC APPLICATION START-UP
By default, (see the \fBARGUMENTS\fP section on how to override this), when
the cluster is formed any applications that have been registered, and are
configured to Auto-start will automatically be started (if possible).

In the case when there are multiple applications that are registered with the
cluster then the order of starting them is not defined. In such cases each
one will be started in turn.

However if an auto-started application has dependencies then these will be
started prior to the auto-start application in question. Hence if you
wish to auto-start multiple applications then the recommendation is to 
autostart one - and have the other as dependencies.

Support for recursive dependencies will be introduced in later versions
of the software.

.SH PARALLEL APPLICATION STARTS [EXPERIMENTAL]
If the environment has auto-start applications, but there are no start-up
dependencies with these applications then the administrator can make use
of parallel application starts. This will start all applications at the 
same time - which on more powerful servers can reduce the time before all
applications are available.

For information on how to configure this please view the \fIclconf.xml(5)\fP
manual page. It should be noted that this is still classed as experimental
though this status should be removed for later 1.2 based releases.

.SH MANUALLY FORMING THE CLUSTER
It should be noted that the \fIclform(1M)\fP utility is basically a 
convenience tool for forming the cluster under normal conditions. If the
administrator wishes for more direct control over the cluster, they can
use the you should continue to \fIcldaemon(1M)\fP command directly. 

For example to start the cluster normally (given commands on "servera" where
the other node is "serverb"), you might run the following commands:

.TS
l.
servera# ssh serverb /sbin/cluster/cldaemon --form --detach 
servera# /sbin/cluster/cldaemon --form --detach
.TE

You can validate that the cluster starts correctly by either examining the 
log files, (by default in the /var/log/cluster directory on each host), or
be running the \fIclstat(1M)\fP utility.

If one of the nodes is not available you would need to include the "--force" 
option to allow the cluster to form using a single node. It is recommended
that under such conditions you reduce the timeout waiting for the cluster
to form, using the "--maxdelay" option. For example:

.TS
l.
serverb# /sbin/cluster/cldaemon --force --maxdelay=10 --detach
.TE

.SH ARGUMENTS
.TP 4
.B --force
This will attempt form the cluster, (or join it if it is already
running), even if the time difference between the two nodes is larger 
than 10 minutes. (For reasons why this is not recommended, please
see the \fBTIME DEPENDENCIES\fP section below).
.TP
.B --noapps
Do not start any applications that are registered to auto-start. The
default behaviour is to start such applications, (and any dependencies
they may indicate).
.TP
.B --join
The default behaviour for the command is to attempt to form the
cluster using the two nodes. The \fB--join\fP option is used to 
get one of the nodes to join the cluster that is already running.

It does not matter which node this command is run on - it will
determine which node in the cluster is running and which is not, 
and take the necessary actions.
.TP
.B --config
Rather the use the configuration file /etc/cluster/clconf.xml as the
file containing the cluster configuration use the specified file
instead. Rarely used now.
.TP
.B --debug
Start the cluster daemons with the \fB--debug\fP flag to gather mor
information. Typically this is only used by developers when 
attempting to resolve problems.
.TP
.B --nochecksums
Allows the cluster formation to occur even if the checksums for the
cluster configurations do not match. Using this argument is not
recommended - \fIclbuild(1M)\fP can always be run - whether the cluster
is up and running or not. Indeed possibly the only case might be when the
configuration has been changed and other node is not available - hence
it is necessary to form the cluster without being able to perform a 
rebuild.
.TP
.B --nolocking
Simply passes this argument to the cluster daemons to ensure that
no locking occurs for any cluster operations in the cluster. This is
only really suitable when the cluster only contains a single application.

It is recommended that this is not used unless a compelling reason can be
found not to perform such locking.
.TP
.B --nodrbdcheck
Before attempting to form the cluster the \fIclform(1M)\fP utility will
attempt to validate that a suitable DRBD module exists for the running 
kernel. If it does not it will attempt to compile and install it automatically.

Further if a new .tar.gz of the DRBD software is available in /usr/local/cluster
then the version that is currently installed it will also attempt to unpack it,
compile and install it.

The \fB--nodrbdcheck\fP argument will turn off this convenience feature.

.SH TIME DEPENDENCIES
By default unless the times on the two machines are within 10 minutes
of each other the cluster will fail to form. This can be overriden
by using the \fB--force\fP option, though this is not recommended.

The reason for required almost identical times on the machines is that
it records the time when a particular application starts on the node,
and then uses this information if both nodes do not agree on the
last status of an application. Hence if the times are incorrect it
might actually choose the status from the wrong node, obviously leading
to potential access consistency problems.

It is also worth noting that when waiting for a cluster to form the 
timout defaults to 300 seconds (5 minutes). This time should cover the 
difference in between a complete reboot of the slowest machine in the
cluster, but can be shorten if you know the other node in the cluster
is not going to be available.

.SH EXIT STATUS
The \fIclform(1M)\fP utility makes use of many error codes, but in summary
it will return a non-zero number for an error or zero if the information
requested has been successfully processed.

.SH FILES
The manual contains a complete list of files that are important to the
formation of the cluster, as well as the starting, stopping and 
management of the applications contained. The list below contains some
of the more important ones only.

.TP 4
.B /var/log/cluster/cldaemon-clustername
This log contains the local cldaemon messages. The 'clustername'
portion is actually the name assigned to the cluster. The amount
of detail in here is determined by the use of the '--verbose'
option on the cldaemon(1M) command. Using the \fIclform(1M)\fP 
command will ensure the --verbose option is always present.
.TP
.B /var/log/cluster/clstartapp-appname
The name which contains the log output of the specified application
when it starts up. In a similar way to the cluster log file, this
file contents depend on whether the '--verbose' option is used, and
of course when using the \fIclform(1M)\fP command this option is 
turned on.

.SH SEE ALSO
.TS
l l.
clbuild(1M)	- Build / Validate cluster topology
clbuildapp(1M)	- Build / Synchronise cluster application 
clstat(1M)	- Show cluster status information
clstart(1M)	- Start cluster on machine boot
cldeamon(1M)	- Cluster status Daemon
clstartapp(1M)	- Start a clustered application
clrunapp(1M)	- High level tool to start clustered application
clhaltapp(1M)	- Halt a clustered application
clconf.xml(5)	- Overall cluster topology configuration file
appconf.xml(5)	- Configuration of an application used by the cluster
.TE

.SH NOTES
If this program does fail the administrator is recommended to view
the cluster and application files, as described in the \fBFILES\fP
section above.

.SH AUTHOR
The \fIclform(1M)\fP utility was written by Simon Edwards, 2003-2006. The
author can be contacted via the website mentioned below.

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
\fBhttp://www.linuxha.net\fP for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

